open-api

1. 接口
- 1.1. 发送消息通知
- 1.2. 资源上传接口
- 1.3. 注册小程序未读数接口
- 1.4. 租户相关接口
  - 1.4.1. 查询租户信息接口
  - 1.4.2. 开通租户接口
  - 1.4.3. 租户续费接口
  - 1.4.4. 删除租户接口
1. 接口AK-SK签名验证
- 2.1. 生成签名
  - 2.1.1. 后端java签名示例
  - 2.1.2. 前端JavaScript签名示例

1. 接口

1.1. 发送消息通知

接口：POST http://[supLink ip地址]:8042/suplink/openapi/v1/notify

请求参数

参数	类型	必须	示例值	说明
appId	String	是	A84BB90914CA	后台管理创建应用的appId，不传或者查不到默认为未知应用。
toUsers	Array	是	[ "admin","test106" ]	接收消息的用户名（supOS的用户名）
msg	对象	是	"msg": { "type": "default", "title": "1级报警", "content": "dev_ningbo_mirror.电流随机数值为 24.96>1.0，发生一级报警", "link": "https://www.baidu.com" }	消息内容支持：卡片消息、文本消息、图片消息、视频消息、语言消息、文件消息

接口返回

{
    "code": 200,
    "message": "success",
    "content": {
        "messageId": "931870a9-888c-4030-9709-198b104e59c6"
    }
}

卡片消息参数说明

{
  "appId": "", // 对应的suplink 小程序appid
  "msg": {     // 消息体
    "content": "你好",  // 消息通知内容，必填
    "link": "https://www.baidu.com",     // 点击消息通知跳转链接地址，非必填
    "msgType": "card_msg",// 卡片消息类型，必填
    "title": "卡片消息", // 消息通知标题，非必填
    "type": "default"  // 卡片消息UI模板，默认为default，非必填
  },
  "toUsers": [ "test100"] // 发送目标用户，必填
}

文本消息参数说明

{
  "appId": "", // 对应的suplink 小程序appid
  "msg": {     // 消息体
    "content": "文本消息内容",  // 文本消息内容，必填
    "msgType": "text_msg"// 文本消息类型，必填
  },
  "toUsers": [ "test100"] // 发送目标用户，必填
}

多媒体消息参数说明

{
  "appId": "", // 对应的suplink 小程序appid
  "msg": {     // 消息体
    "msgType": "image_msg",// 必填，图片消息类型：image_msg，视频消息类型：video_msg，语音消息类型：voice_msg，文件消息类型：file_msg
    "resourceId": 12 // 多媒体资源上传到supLink后返回的resourceId
  },
  "toUsers": [ "test100"] // 发送目标用户，必填
}

1.2. 资源上传接口

接口：POST http://[supLink ip地址]:8042/suplink/openapi/v1/resource/upload

请求参数

参数	类型	必须	示例值	说明
file	文件	是		form-data数据

接口返回

{
  "code": 200,
  "content": {
    "downloadUrl": "/zhizhi/static/resource/load/redirect/openapi/2020-10/5bcf27b5-03b8-4eaa-a908-61ed7a8c37c7.pdf/suplink2.pdf", // 资源下载地址
    "resourceId": 24    // 资源id
  },
  "message": "success"
}

1.3. 注册小程序未读数接口

接口：POST http://[supLink ip地址]:8042/suplink/openapi/v1/app/minapp/registry/unread

请求参数

参数	类型	必须	示例值	说明
appId	String	是		小程序appId
unread	Long	是	10	全局未读数，所有用户一样
unreadOfUser	对象	否	{ "admin": 5, "test001": 1, "test002": 2 }	根据用户区分的未读数，会覆盖全局未读数

参数举例

{
// 小程序appId
  "appId": "7e0f00cb-3a2c-4a54-b9b8-a0fdbcd315ff",
// 全局未读数，所有用户一样
  "unread": 10,
// 根据用户区分的未读数，会覆盖全局未读数
  "unreadOfUser": {
    "admin": 5,
    "test001": 1,
    "test002": 2
  }
}

1.4. 租户相关接口

1.4.1. 查询租户信息接口

接口：POST http://[supLink ip地址]:8042/open-api/suplink/tenant/info

请求参数

参数	类型	必须	示例值	说明
tenantId	String	是	960b98e6bbf9427cb93b71f9ba9aa24e	supLink租户Id

参数举例

{
  "tenantId": "960b98e6bbf9427cb93b71f9ba9aa24e"
}

接口返回

{
  "code": 200,
  "data": {
    "endDate": "20579193215", // 过期时间，单位为秒
    "startDate": "1618886946", // 开始时间，单位为秒
    "state": "SUCCESS",     // 租户状态（SUCCESS/FAILURE/PENDING）
    "tenantId": "960b98e6bbf9427cb93b71f9ba9aa24e"   // supLink租户id
  },
  "msg": "success"
}

1.4.2. 开通租户接口

接口：POST http://[supLink ip地址]:8042/open-api/suplink/tenant/opening

请求参数

参数	类型	必须	示例值	说明
instanceName	String	是	eco-krn2	格式：租户域名前缀-supOS租户标识
startDate	String	是	1618886946	开始时间，单位为秒
endDate	String	是	20579193215	过期时间，单位为秒
instanceId	String	否		暂时没有用

参数举例

{
  "endDate": "20579193215", // 过期时间，单位为秒
  "instanceId": "",   // 暂时无用
  "instanceName": "eco-krn2", // 格式：租户域名前缀-supOS租户标识
  "startDate": "1618886946" // 开始时间，单位为秒
}

接口返回

{
  "code": 200,
  "data": {
    "tenantId": "960b98e6bbf9427cb93b71f9ba9aa24e" // supLink租户id
  },
  "msg": "success"
}

1.4.3. 租户续费接口

接口：POST http://[supLink ip地址]:8042/open-api/suplink/tenant/renew

请求参数

参数	类型	必须	示例值	说明
tenantId	String	是	960b98e6bbf9427cb93b71f9ba9aa24e	supLink租户id
endDate	String	是	20579193215	过期时间，单位为秒

参数举例

{
  "endDate": "20579193215", // 过期时间，单位为秒
  "tenantId": "960b98e6bbf9427cb93b71f9ba9aa24e" // supLink租户id
}

接口返回

{
  "code": 200,
  "msg": "success"
}

1.4.4. 删除租户接口

接口：POST http://[supLink ip地址]:8042/open-api/suplink/tenant/delete

请求参数

参数	类型	必须	示例值	说明
tenantId	String	是	960b98e6bbf9427cb93b71f9ba9aa24e	supLink租户id

参数举例

{
  "tenantId": "960b98e6bbf9427cb93b71f9ba9aa24e" // supLink租户id
}

接口返回

{
  "code": 200,
  "msg": "success"
}

2. 接口AK-SK签名验证

Open Api 需要通过AK-SK签名验证才能调用。 签名参数说明

AK: suplink
SK: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
签名算法：HMAC-SHA256

请求接口签名header格式：Authorization: Sign - Signature是生成的签名。

2.1. 生成签名

组装签名源：

CanonicalRequestString = 
      HTTPSchema + "\n"                   // 请求方法名
      HTTPURI + "\n"                      // 请求URI
      HTTPContentType + "\n"              // 请求Content-Type
      CanonicalQueryString + "\n"         // 请求参数
      CanonicalCustomHeaders + "\n"       // 请求头

HTTPSchema：即HTTP请求的Method，如GET、POST、PUT、DELETE等，大写字母。

HTTPURI：/iam/v1/resource (如：HTTP请求的URI地址：http://192.168.8.84:8042/iam/v1/resource?accountId=2344654656)

HTTPContentType：HTTP协议头中的“Content-Type”的值，如application/json。

注意：如果是上传文件Content-Type值要显示设置为Content-Type:multipart/form-data; boundary=123asdw,其中boundary值可以是随机的字符串，如果不设置就会自己动态生成，就会导致aksk校验不通过。

CanonicalQueryString：即HTTP请求地址中的QueryParams。

注意：如果没有参数也需要拼接换行符”\n”。
例：http://localhost:80/demo?B=1&c=2&a=3&D=4
CanonicalQueryString: a=3&b=1&c=2&d=4
拼接步骤:

列举所有的QueryParams，结构KV形式。

将K进行字母小写处理，并按照字母序（ASCLL码序）进行排序。

根据排序后的Key组装CanonicalQueryString。

注意V不需要排序和小写转换。

CanonicalCustomHeaders：即HTTP协议头中所有“自定义”（X-MC-为前缀）Header。

注意：如果没有自定义header也需要拼接换行符”\n”。例：x-mc-data:20190101T135959Z;x-mc-traceid:eb641bc19dc140f802ff0d2aa657c653 拼接步骤：

列举所有的以X-MC-为前缀的请求头。

将HeaderName进行字母小写处理，并按照字母序（ASCLL码序）进行排序。

多个Header之间以“;”进行分隔并串联。

然后对CanonicalRequestString加密生成签名，参考下面代码示例

2.1.1. 后端java签名示例

以推送接口为例：http://192.168.8.84:8042/suplink/openapi/v1/notify

demo1

CanonicalRequestString如下所示

demo2

计算后签名如下所示：

demo3

推送接口签名请求头设置：
Authorization: Sign <AccessKey>-<Signature>
示例：Authorization: Sign suplink-6bed987e28ee81a108586c3ff726dd19c48fd704e69a98a76ab3ad58f41e56ed

Sign: 固定前缀字符串
AccessKey：账户ID，固定为suplink
-：分隔符
Signature: 通过算法生成数字签名

2.1.2. 前端JavaScript签名示例

jsdemo